Node / meshtastic / Meshtastic-Android / files / core / repository / src / commonMain / kotlin / org / meshtastic / core / repository / RadioInterfaceService.kt

Displaying Raw • Download

T8b949e/*

* Copyright (c) 2026 Meshtastic LLC

*

* This program is free software: you can redistribute it and/or modify

* it under the terms of the GNU General Public License as published by

* the Free Software Foundation, either version 3 of the License, or

* (at your option) any later version.

*

* This program is distributed in the hope that it will be useful,

* but WITHOUT ANY WARRANTY; without even the implied warranty of

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

* GNU General Public License for more details.

*

* You should have received a copy of the GNU General Public License

* along with this program. If not, see <https://www.gnu.org/licenses/>.

*/

Tff7b72package T7ee787org.meshtastic.core.repository

Tff7b72import T7ee787kotlinx.coroutines.CoroutineScope

Tff7b72import T7ee787kotlinx.coroutines.flow.Flow

Tff7b72import T7ee787kotlinx.coroutines.flow.StateFlow

Tff7b72import T7ee787org.meshtastic.core.model.ConnectionState

Tff7b72import T7ee787org.meshtastic.core.model.DeviceType

Tff7b72import T7ee787org.meshtastic.core.model.InterfaceId

Tff7b72import T7ee787org.meshtastic.core.model.MeshActivity

T8b949e/**

* Interface for the low-level radio interface that handles raw byte communication.

*

* This is the **transport layer** — it manages the raw hardware connection (BLE, TCP, Serial, USB) to a Meshtastic

* radio. Its [connectionState] reflects whether the physical link is up or down, **before** any handshake or

* config-loading logic is applied.

*

* **Important:** UI and feature modules should **never** observe [connectionState] directly. Instead, they should use

* [ServiceRepository.connectionState], which is the canonical app-level connection state that accounts for handshake

* progress, light-sleep policy, and other higher-level concerns. The only legitimate consumer of this transport-level

* flow is [MeshConnectionManager], which bridges transport state changes into the app-level

* [ServiceRepository.connectionState].

*

* @see ServiceRepository.connectionState

*/

Tff7b72interface T56d364RadioInterfaceService Tb4b4b4: Te6edf3RadioTransportCallback Tb4b4b4{

T8b949e/** The device types supported by this platform's radio interface. */

Tff7b72val Te6edf3supportedDeviceTypesTb4b4b4: Te6edf3ListTff7b72<Te6edf3DeviceTypeTff7b72>

T8b949e/**

* Transport-level connection state of the radio hardware.

*

* This flow reflects the raw state of the physical link (BLE, TCP, Serial, USB):

* - [ConnectionState.Connected] — the transport link is established

* - [ConnectionState.Disconnected] — the transport link is down (permanent)

* - [ConnectionState.DeviceSleep] — the transport link is down (transient, device sleeping)

*

* **This is NOT the canonical app-level connection state.** The transport may report [ConnectionState.Connected]

* while the app is still performing the mesh handshake (config + node-info exchange), during which the app-level

* state remains [ConnectionState.Connecting].

*

* Only [MeshConnectionManager] should observe this flow. All other consumers (ViewModels, feature modules, UI) must

* use [ServiceRepository.connectionState].

*

* @see ServiceRepository.connectionState

*/

Tff7b72val Te6edf3connectionStateTb4b4b4: Te6edf3StateFlowTff7b72<Te6edf3ConnectionStateTff7b72>

T8b949e/** Flow of the current device address. */

Tff7b72val Te6edf3currentDeviceAddressFlowTb4b4b4: Te6edf3StateFlowTff7b72<Tffa657String?Tff7b72>

T8b949e/** Whether we are currently using a mock transport. */

Tff7b72fun Td2a8ffisMockTransportTb4b4b4(Tb4b4b4)Tb4b4b4: Tffa657Boolean

T8b949e/**

* Flow of raw data received from the radio.

*

* Emissions preserve the order in which bytes arrived from the hardware — this is required because the firmware

* handshake (initial config packet ordering) depends on strict FIFO delivery. Implementations MUST guarantee

* ordering; do not swap in a [SharedFlow] without preserving order.

*/

Tff7b72val Te6edf3receivedDataTb4b4b4: Te6edf3FlowTff7b72<Te6edf3ByteArrayTff7b72>

T8b949e/** Flow of radio activity events. */

Tff7b72val Te6edf3meshActivityTb4b4b4: Te6edf3FlowTff7b72<Te6edf3MeshActivityTff7b72>

T8b949e/**

* Drains any bytes currently buffered in [receivedData] without emitting them to collectors.

*

* Callers invoke this before attaching a fresh collector after a stop/start cycle so stale bytes buffered while no

* collector was attached do not get replayed ahead of the next session's handshake.

*/

Tff7b72fun Td2a8ffresetReceivedBufferTb4b4b4(Tb4b4b4)

T8b949e/** Sends a raw byte array to the radio. */

Tff7b72fun Td2a8ffsendToRadioTb4b4b4(Te6edf3bytesTb4b4b4: Te6edf3ByteArrayTb4b4b4)

T8b949e/** Initiates the connection to the radio. */

Tff7b72fun Td2a8ffconnectTb4b4b4(Tb4b4b4)

T8b949e/**

* Explicitly tears down the active transport, sending a polite `ToRadio(disconnect = true)` goodbye frame first

* when a transport is live. Safe to call when nothing is connected — implementations must no-op in that case.

* Suspends until the teardown completes.

*/

Tff7b72suspend Tff7b72fun Td2a8ffdisconnectTb4b4b4(Tb4b4b4)

T8b949e/**

* Silent in-place transport restart for handshake stalls: tears down the active transport and re-establishes it in

* place, without touching the connection-request gate or the selected device address.

*

* Both transport families use this recovery path but with different trigger timings: TCP/USB reach it through the

* fast-path watchdog (~12s after the last meaningful handshake packet), while BLE reaches it after the

* retry-exhausted path (~30s/60s watchdog plus a ~15s retry window). In both cases the symptom is identical: the

* transport itself may still be physically [ConnectionState.Connected] (e.g. a TCP socket whose radio firmware has

* stopped responding to `want_config_id`, or a BLE link whose GATT peer has stalled), so flipping app-level state

* to [ConnectionState.Disconnected] alone leaves a split-brain: transport Connected + `connectionRequested=true` +

* a live `RadioTransport` handle, which then blocks same-node reconnect via [setDeviceAddress]'s fast-path. This

* method breaks that deadlock by cycling the transport in place.

*

* Contract:

* - Preserves the selected device address (does not modify [currentDeviceAddressFlow]).

* - Preserves the `connectionRequested` gate; **MUST NOT** clear it. Safe to call concurrently with an explicit

* [disconnect] — the internal gate check makes it a no-op in that case.

* - Safe to call when no transport is running — implementations must no-op.

* - Does **NOT** bypass selected-device validation; the replacement transport is built from the same bonded address

* via the normal start path.

* - Emits ordinary transport-level transitions through the existing [RadioTransportCallback] surface, so observers

* see the transient [ConnectionState.DeviceSleep] state followed by [ConnectionState.Connected] when the

* replacement transport connects. (No [ConnectionState.Connecting] is emitted at the transport layer — that is an

* app-level state set by [MeshConnectionManager], not a transport callback.)

*

* Suspends until the teardown/restart cycle completes.

*/

Tff7b72suspend Tff7b72fun Td2a8ffrestartTransportTb4b4b4(Tb4b4b4)

T8b949e/** Returns the current device address. */

Tff7b72fun Td2a8ffgetDeviceAddressTb4b4b4(Tb4b4b4)Tb4b4b4: Tffa657String?

T8b949e/** Sets the device address to connect to. */

Tff7b72fun Td2a8ffsetDeviceAddressTb4b4b4(Te6edf3deviceAddrTb4b4b4: Tffa657String?Tb4b4b4)Tb4b4b4: Tffa657Boolean

T8b949e/** Constructs a full radio address for the specific interface type. */

Tff7b72fun Td2a8fftoInterfaceAddressTb4b4b4(Te6edf3interfaceIdTb4b4b4: Te6edf3InterfaceIdTb4b4b4, Te6edf3restTb4b4b4: Tffa657StringTb4b4b4)Tb4b4b4: Tffa657String

T8b949e/** Flow of user-facing connection error messages (e.g. permission failures). */

Tff7b72val Te6edf3connectionErrorTb4b4b4: Te6edf3FlowTff7b72<Tffa657StringTff7b72>

T8b949e/** The scope in which interface-related coroutines should run. */

Tff7b72val Te6edf3serviceScopeTb4b4b4: Te6edf3CoroutineScope

Tb4b4b4}